package za.org.jcicada.comms;

/**
 * ICommsBidirectionalQueue.java
 *
 * @author Ernst van Graan
 * @author Robert Crida
 * @author Simon Cross
 *
 * Created on 21 October 2008, 11:25
 */

import java.io.IOException;

import za.org.jcicada.comms.messages.CommsMessage;

/**
 * Provides the necessary functionality for setting up, using and managing
 * two-way network communication using queues.
 */
public interface IConnection {

    /**
     * Initialize the queue with the given listener.
     * <p>
     * Create any infrastructure needed to process messages and set the given
     * listener as the message listener.
     * 
     * @param listener object used to process messages
     * @throws IOException If initializing the queue fails.
     */
    void initialize(IMessageListener listener) throws IOException;

    /**
     * Shut down the queue.
     * <p>
     * Clean up any objects and stop any threads created in initialize.
     * 
     * @throws IOException If shutting down the queue fails.
     */
    void close() throws IOException;

    /**
     * Check if the connection is closed.
     * 
     * @return true if closed.
     */
    boolean isClosed();

    /**
     * Send a message.
     * 
     * @param message The katcomms CommsMessage to send.
     * @throws IOException if an error occurs while sending the message.
     */
    void sendMessage(CommsMessage message) throws IOException;

    /**
     * Access the message listener.
     * 
     * @return the message listener
     */
    IMessageListener getListener();
}
